package com.smart.community.region.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.Result;
import com.smart.community.commons.result.PageResult;
import com.smart.community.region.dto.UnitDTO;
import com.smart.community.region.dto.UnitQueryDTO;
import com.smart.community.region.entity.Unit;
import com.smart.community.region.vo.UnitVO;
import com.smart.community.commons.exception.BusinessException;
import com.smart.community.region.vo.UnitDeleteImpactVO;

import java.util.List;
import java.util.Map;

/**
 * 单元管理服务接口
 * 
 * @author Wu.Liang
 * @since 2024-12-21
 */
public interface IUnitService extends IService<Unit> {

    // ==================== 基础CRUD方法 ====================

    /**
     * 分页查询单元楼列表
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    PageResult<UnitVO> getUnitPage(UnitQueryDTO queryDTO) throws Exception;

    /**
     * 查询单元楼列表
     * 
     * @param queryDTO 查询条件
     * @return 单元楼列表
     */
    List<UnitVO> getUnitList(UnitQueryDTO queryDTO) throws Exception;

    /**
     * 根据ID查询单元楼
     * 
     * @param unitId 单元楼ID
     * @return 单元楼信息
     */
    UnitVO getUnitById(Long unitId) throws Exception;

    /**
     * 根据编码查询单元楼
     * 
     * @param unitCode 单元楼编码
     * @return 单元楼信息
     */
    UnitVO getUnitByCode(String unitCode) throws Exception;

    /**
     * 新增单元楼
     * 
     * @param unitDTO 单元楼信息
     * @return 操作结果
     */
    Result<UnitVO> addUnit(UnitDTO unitDTO) throws Exception;

    /**
     * 更新单元楼
     * 
     * @param unitDTO 单元楼信息
     * @return 操作结果
     */
    Result<UnitVO> updateUnit(UnitDTO unitDTO) throws Exception;

    /**
     * 删除单元楼
     * 
     * @param unitId 单元楼ID
     * @return 操作结果
     */
    Result<Void> deleteUnit(Long unitId) throws Exception;

    /**
     * 批量删除单元楼
     * 
     * @param unitIds 单元楼ID列表
     * @return 操作结果
     */
    Result<Void> batchDeleteUnit(List<Long> unitIds) throws Exception;

    /**
     * 更新单元状态
     * 
     * @param unitId 单元ID
     * @param status 状态
     * @return 是否成功
     */
    boolean updateUnitStatus(Long unitId, Integer status) throws Exception;

    /**
     * 批量更新单元状态
     * 
     * @param unitIds 单元ID列表
     * @param status 状态
     * @return 是否成功
     */
    boolean batchUpdateUnitStatus(List<Long> unitIds, Integer status) throws Exception;

    // ==================== 查询方法 ====================

    /**
     * 根据楼栋ID查询单元楼列表
     * 
     * @param buildingId 楼栋ID
     * @return 单元楼列表
     */
    List<UnitVO> getUnitByBuildingId(Long buildingId) throws Exception;

    /**
     * 根据楼栋ID获取单元列表（返回Unit实体）
     * 
     * @param buildingId 楼栋ID
     * @return 单元列表
     */
    List<Unit> getUnitsByBuildingId(Long buildingId) throws Exception;

    /**
     * 根据社区ID集合查询单元列表
     * 
     * @param communityIds 社区ID集合
     * @param buildingIds 楼栋ID集合（可选）
     * @return 单元列表
     */
    List<Unit> getUnitsByCommunityIds(List<Long> communityIds, List<Long> buildingIds) throws Exception;

    /**
     * 根据社区ID集合查询单元，按楼栋分组返回
     * 
     * @param communityIds 社区ID集合
     * @param buildingIds 楼栋ID集合（可选）
     * @return 按楼栋分组的单元Map
     */
    Map<Long, List<Unit>> getUnitsGroupedByBuilding(List<Long> communityIds, List<Long> buildingIds) throws Exception;

    /**
     * 根据用户权限获取单元列表
     * 
     * @param userId 用户ID
     * @return 有权限的单元列表
     */
    List<Unit> getUnitsByUserPermission(Long userId) throws Exception;

    /**
     * 获取单元下的房户列表
     * 
     * @param unitId 单元ID
     * @return 房户列表
     */
    List<Object> getHouseholdsByUnit(Long unitId) throws Exception;

    // ==================== 统计方法 ====================

    /**
     * 统计单元数量
     * 
     * @param buildingId 楼栋ID（可选）
     * @return 单元数量
     */
    Long countUnits(Long buildingId) throws Exception;

    /**
     * 获取单元统计信息
     * 
     * @param unitId 单元ID
     * @return 统计信息
     */
    Object getUnitStats(Long unitId) throws Exception;

    // ==================== 验证方法 ====================

    /**
     * 检查单元楼编码唯一性
     * 
     * @param unitCode 单元楼编码
     * @param excludeUnitId 排除的单元楼ID
     * @return 是否唯一
     */
    boolean checkUnitCodeUnique(String unitCode, Long excludeUnitId) throws Exception;

    /**
     * 检查单元编码是否存在
     * 
     * @param unitCode 单元编码
     * @param excludeId 排除的单元ID
     * @return 是否存在
     */
    boolean existsByUnitCode(String unitCode, Long excludeId) throws Exception;

    // ==================== 缓存方法 ====================

    /**
     * 清除单元缓存
     * 
     * @param unitId 单元ID
     */
    void clearUnitCache(Long unitId) throws Exception;

    /**
     * 清除所有单元缓存
     */
    void clearAllUnitCache() throws Exception;

    // ==================== 数据权限业务接口 ====================

    /**
     * 根据楼栋ID集合获取单元ID集合
     * 供其他模块调用，用于数据权限查询
     * 
     * @param buildingIds 楼栋ID集合
     * @return 单元ID集合
     */
    List<Long> getUnitIdsByBuildingIds(List<Long> buildingIds) throws Exception;

    /**
     * 根据楼栋ID获取单元ID列表
     * 供其他模块调用，用于数据权限查询
     * 
     * @param buildingId 楼栋ID
     * @return 单元ID列表
     */
    List<Long> getUnitIdsByBuildingId(Long buildingId) throws Exception;

    /**
     * 删除单元（带关联处理）
     * 
     * @param unitId 单元ID
     * @param currentUserId 当前用户ID
     * @return 删除结果
     * @throws BusinessException 业务异常
     */
    String deleteUnitWithRelations(Long unitId, Long currentUserId) throws BusinessException;

    /**
     * 批量删除单元（带关联处理）
     * 
     * @param unitIds 单元ID列表
     * @param currentUserId 当前用户ID
     * @return 删除结果
     * @throws BusinessException 业务异常
     */
    String batchDeleteUnitsWithRelations(List<Long> unitIds, Long currentUserId) throws BusinessException;

    /**
     * 检查删除影响
     * 
     * @param unitId 单元ID
     * @return 删除影响分析
     */
    UnitDeleteImpactVO checkDeleteImpact(Long unitId);

    /**
     * 根据楼栋ID获取单元列表
     * 
     * @param buildingId 楼栋ID
     * @return 单元列表
     */
    List<UnitVO> getUnitListByBuilding(Long buildingId);

    // ==================== Feign接口专用方法 ====================

    /**
     * 根据单元ID获取单元信息（Feign接口专用，跳过权限验证）
     * 
     * @param unitId 单元ID
     * @return 单元信息
     */
    com.smart.community.feign.region.dto.UnitInfoDTO getUnitByIdForFeign(Long unitId) throws Exception;

    /**
     * 批量根据单元ID获取单元信息（Feign接口专用，跳过权限验证）
     * 
     * @param unitIds 单元ID列表
     * @return 单元信息列表
     */
    List<com.smart.community.feign.region.dto.UnitInfoDTO> getUnitsByIdsForFeign(List<Long> unitIds) throws Exception;

} 